Skip to content

feat(tunnel): add configuration hot reload support #1582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
lexfrei wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(tunnel): add configuration hot reload support #1582

lexfrei wants to merge 1 commit into from

Conversation

@lexfrei
Copy link

@lexfrei lexfrei commented Jan 13, 2026 •
edited
Loading

Summary

Add support for hot reloading configuration without restarting cloudflared. This enables updating ingress rules, warp-routing settings, and origin request configuration on the fly.

Related issues: #240, #301, #512, #965

Changes

  • Add LocalConfigWatcher component that monitors config.yaml for changes via fsnotify
  • Add SIGHUP signal handling to trigger manual configuration reload
  • Reuse existing Orchestrator.UpdateConfig() mechanism (already used for remote-managed tunnels)
  • Include 500ms debounce to handle rapid file changes from editors

Usage

# Automatic: edit config.yaml while cloudflared is running
# Changes are detected and applied within ~500ms

# Manual: send SIGHUP signal
kill -HUP $(pgrep cloudflared)

What can be hot-reloaded

Parameter Hot Reload
ingress rules ✅
warp-routing ✅
originRequest ✅
tunnel UUID ❌
credentials-file ❌
protocol ❌

Limitations

  • Only works for locally managed tunnels (not token-based)
  • Invalid configuration is rejected and previous config is preserved
  • Immutable parameters (tunnel UUID, credentials) require restart

Test plan

  • Unit tests for config conversion (TestConvertLocalConfigToJSON*)
  • Unit tests for validation (TestValidateLocalConfig*)
  • Unit tests for file watcher (TestLocalConfigWatcher*)
  • Unit tests for SIGHUP handling (TestSignalShutdown)
  • Manual testing with local tunnel

@lexfrei lexfrei force-pushed the feat/hot-reload-config branch 3 times, most recently from f25e7e7 to f8b2a3a Compare January 13, 2026 10:40
@lexfrei lexfrei marked this pull request as ready for review January 13, 2026 10:40
@lexfrei lexfrei force-pushed the feat/hot-reload-config branch from f8b2a3a to 2e8a997 Compare January 13, 2026 10:43
@lexfrei @claude
feat(tunnel): add configuration hot reload support
7939127 
Add hot reload capability for locally-managed tunnels. When a config file
is specified (without --token), cloudflared now watches for changes and
automatically reloads the configuration.

Features:
- File watching via fsnotify with 500ms debounce
- Fallback polling every 30s for symlink rotation (Kubernetes ConfigMaps)
- Manual reload via SIGHUP signal
- Graceful handling of invalid configs (keeps current config)
- Thread-safe with TryLock to skip concurrent reloads

New files:
- orchestration/local_config.go: Config file reading and validation
- orchestration/local_watcher.go: File watcher with reload logic

Co-Authored-By: Claude <[email protected]>
Signed-off-by: Aleksei Sviridkin <[email protected]>
@lexfrei lexfrei force-pushed the feat/hot-reload-config branch from 9ff8814 to 7939127 Compare January 14, 2026 17:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@lexfrei